Skip to content

fix: bin GPU heatmap in Web Mercator so heat lines up with airports (#15) - #21

Merged
GeoBradDev merged 6 commits into
mainfrom
issue-15-gpu-heatmap-misregistered
Nov 8, 2026
Merged

GeoBradDev merged 6 commits into
mainfrom
issue-15-gpu-heatmap-misregistered

Conversation

@GeoBradDev

Copy link
Copy Markdown
Owner

Summary

The GPU heatmap's accumulate shader binned airports into an equirectangular grid (row = (90 - lat) / 180 * 512), but the deck.gl BitmapLayer draws that image stretched linearly in Web Mercator Y between +/-85.051129. That pushed heat toward the poles: an airport at 60N drew near 76N.

The shader now bins latitude in Web Mercator Y, clamped to +/-85.051129, and the bitmap keeps its Mercator bounds. A new helper module, src/layers/heatmapProjection.js, is the one source for the latitude limit, the grid size, the lat/lon-to-cell formulas and HEATMAP_BOUNDS. The shader's WGSL lonToCol/latToRow are generated from its constants, and buildLayers takes its bounds from it.

I chose not to use _imageCoordinateSystem: COORDINATE_SYSTEM.LNGLAT with [-180, -90, 180, 90] bounds. In deck.gl 9.4.1 that prop is experimental. Its fragment shader clamps latitude to +/-89.9, while quad corners at +/-90 project to infinite Mercator Y. No unit test can pin its behavior in the non-interleaved overlay.

Unchanged: the color ramp, the run-once behavior, buffer lifetimes, the COLORIZE shader, and the earlier a11y, layout, contrast, benchmark and RENDER work.

Plan

docs/plans/2026-11-07-issue-15-gpu-heatmap-misregistered.md, committed at 8071492 before any code. Revised during the work:

  • 35f7193 and 7589af6 added the WGSL translator test after review found that no test ran the generated shader formula.
  • d710501 aligned the plan's wording with that test.
  • The Risks line now describes the order the code really uses: clamp latitude, floor, then clamp the row.

Test evidence

Gate on 7589af6 (d710501 changes only the plan doc), all exit 0:

  • npm ci: 0 vulnerabilities
  • npm run lint: clean
  • npm test: 32 files, 290 tests passed
  • npm run build: built; the existing chunk-size warning remains
  • npm audit --omit=dev --audit-level=high: 0 vulnerabilities

New tests:

  • src/layers/heatmapProjection.test.js sweeps latitudes from -80 to 80. For each, the row the helper picks, drawn linearly in Mercator Y over HEATMAP_BOUNDS, covers that latitude. It also checks reference points and clamping at +/-85.051129, +/-90 and beyond.
  • src/layers/heatmapProjection.wgsl.test.js translates the generated WGSL to JS and checks it against the JS helpers. In float64 the results must match exactly. In f32 emulation, rows and columns must stay in the grid, extreme latitudes must land on the first or last row, and sweeps must stay within one cell. Each of these mutations makes the test fail: / 2.0 to * 2.0, dropping 1.0 -, dropping + 180.0, and changing the row clamp 511.0 to 512.0 or 0.0 to -5.0.
  • src/layers/index.test.js: the heatmap layer uses HEATMAP_BOUNDS and sets no _imageCoordinateSystem.
  • src/hooks/useGPUHeatmap.test.js: the shader contains the generated binning code, and the old (90.0 - lat) / 180.0 is gone.

Live drive, Playwright Chromium with a SwiftShader WebGPU adapter (--enable-unsafe-webgpu --use-webgpu-adapter=swiftshader), HEATMAP and AIRPORTS on:

  • Implementer, at about 7N (West Africa), 39N (US mid-Atlantic), 63N (Scandinavia) and 63N (Alaska):
    • Hot spots sit on the airport dots.
    • The largest gap between map.project([lon, lat]) and the drawn center of the airport's row is 8.81 px, against a 22.6 px cell. The old code was off by up to 1443 px.
    • In the decoded GPU image, 512,701 of 512,729 cells match the JS helper.
    • The shader compiles with no validation errors.
    • Without WebGPU the app runs and the heatmap toggle stays hidden.
  • Independent verifier, with its own scripts and Mercator math:
    • The GPU image overlaps its own binning at 0.9977, with a best row shift of 0. The old code needed a 40-row shift.
    • On screen, the offset between heat and dots is at most 2 px after the fix, against 39 to 300 px before, at 7N, 39N, 63N, Alaska and 33.9S.
    • Layer toggles work by keyboard and click, and the airport popup opens and closes.
    • No console errors.

Review findings

First round: three Claude finders (Bugs/Compliance, Security, outside-the-diff) and two Fable finders (Bugs/Compliance, edge cases).

  • Fixed: no test ran the generated WGSL formula. Reported by Claude (security lens) and Fable (edge-case lens), and noted by a third reviewer. A confirm finder agreed. Fixed in 35f7193.
  • Fixed: the WGSL test ran only in float64. In f32, the latitude -85.051129 gives a row fraction of exactly 1, so the row clamp was never tested. The test for unknown tokens also threw for the wrong reason. Reported by Claude in the first delta round. Fixed in 7589af6.
  • Dismissed: "live drive evidence missing" (Fable, Claude). The evidence is above.
  • Left as notes:
    • The test translator reads integer literals as floats. A hand edit like * (1 / 2) would pass the test but be integer division on the GPU. This can't happen today because the generator writes every literal with a decimal point. Raised by Claude in the second delta round. I left it rather than start another fix round.
    • The test's u32() throws on negative values, which is stricter than WGSL's saturation.
    • HEATMAP_BOUNDS is a mutable array; Object.freeze would protect it.
    • The JS helpers and WGSL handle NaN differently. Unreachable, because useAirports drops non-finite coordinates.
    • Cells are twice as tall as wide (1024x512 over a square Mercator world).
    • Airports beyond +/-85.05 clamp to the edge rows.
    • At real colors the heat is very faint outside dense regions, because the ramp scales to the single densest cell. This predates the fix and is outside this issue.

Docs reconciled

  • README.md: no change needed. No line became false: "1024 x 512 grid" still holds, and the layout block lists selected paths. I tried adding a projection sentence and a layout entry, then dropped both after doc review.
  • CLAUDE.md: no change needed.
  • Plan: wording aligned with the translator test (d710501).
  • ADR: none.

Closes #15

🤖 Generated with Claude Code

https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf

GeoBradDev and others added 6 commits November 7, 2026 21:00
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…ment (#15)

The accumulate shader bins latitude linearly over [-90, 90] while the
BitmapLayer stretches the image linearly in Mercator Y over +/-85.051129,
so hot spots drift north away from airports. These tests pin a shared
projection helper, its generated WGSL, and the layer bounds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…15)

The accumulate shader mapped latitude linearly over [-90, 90], but the
BitmapLayer draws the image linearly in Mercator Y over +/-85.051129,
so heat drifted north of airports at mid and high latitudes. A new
heatmapProjection module owns the latitude limit, grid size, bounds,
and lat-to-row formula, and generates the shader's binning WGSL from
those constants so the two cannot drift apart again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
The WGSL lonToCol and latToRow bodies restate the formulas in shader
syntax, and no test ran them, so a broken shader formula stayed green.
The new test translates the generated WGSL into JS with a strict
translator that rejects unknown tokens, then checks it against the JS
helpers at reference points, past the Mercator and polar limits, and
over full lat and lon sweeps. The plan now records this coverage and
describes the row clamping as the code does it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
In float64 the south limit gives a row fraction just under 1, so the
shader's row clamp was never exercised; on the GPU, in f32, it is
exactly 1 and the clamp is what keeps the row inside the grid. The
translator is now a small parser that can emit f32-rounded JS, and new
tests assert rows and columns stay in range, extremes land on the edge
rows and columns, and sweeps stay within one cell of the JS helpers.
Each translator rejection test now asserts the error for its own path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
@GeoBradDev
GeoBradDev merged commit fbe4fdb into main Nov 8, 2026
1 check passed
@GeoBradDev
GeoBradDev deleted the issue-15-gpu-heatmap-misregistered branch November 8, 2026 03:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

GPU heatmap is misregistered: equirectangular grid drawn as a Mercator-stretched bitmap

1 participant